{
 "cells": [
  {
   "cell_type": "markdown",
   "metadata": {},
   "source": [
    "# FAQ\n",
    "\n",
    "Frequently Asked Questions (FAQ)."
   ]
  },
  {
   "cell_type": "markdown",
   "metadata": {},
   "source": [
    "## No plot appears\n",
    "\n",
    "On the command line, add `--show`.\n",
    "In Jupyter notebooks, use:\n",
    "\n",
    "```\n",
    "openpifpaf.show.Canvas.show = True\n",
    "openpifpaf.show.Canvas.image_min_dpi = 200\n",
    "```"
   ]
  },
  {
   "cell_type": "markdown",
   "metadata": {},
   "source": [
    "## Why evaluate with 641px instead of 640px?\n",
    "\n",
    "OpenPifPaf uses the standard convention of PyTorch models to pad convolutions. \n",
    "Let's start with an example: a single layer of a 3x3 conv with stride 2 that is padded with 1. For an output feature map of size 2x2, the input must be of size 3x3. This generalization holds: the input must be of size `(nx * stride + 1, ny * stride + 1)`.\n",
    "The models that OpenPifPaf uses have an intermediate layer with stride 16. Therefore, good input image sizes are multiples of 16 plus 1. \n",
    "\n",
    "It is usually not a problem if the input size is not perfect. There will just be a small margin on the right side and bottom of the image that is not \"covered\" by a feature map cell.\n",
    "\n",
    "For more info, see the section on {ref}`coordinate-system`."
   ]
  },
  {
   "cell_type": "markdown",
   "metadata": {},
   "source": [
    "## Installation Problem\n",
    "\n",
    "This project uses continuous integration testing (CI). That means that a set of \n",
    "unit and integration tests is run on multiple versions of Linux, MacOSX and \n",
    "Windows for every code change. The result of these tests is here: \n",
    "[GitHub Action Tests](https://github.com/openpifpaf/openpifpaf/actions/workflows/tests.yml) \n",
    "and click on the latest test for the main branch to see something like this:\n",
    "\n",
    "![github action test overview](images/githubtests.png)\n",
    "\n",
    "You can click on a build job to see its terminal output. The terminal output \n",
    "shows all steps from cloning the repository, installing PyTorch, installing \n",
    "OpenPifPaf to running linting and the actual tests.\n",
    "If you think the list of platforms and Python versions is outdated and you want \n",
    "a particular combination be added to this list, please file a \n",
    "[GitHub issue](https://github.com/openpifpaf/openpifpaf/issues)."
   ]
  },
  {
   "cell_type": "markdown",
   "metadata": {},
   "source": [
    "## Matplotlib Backend\n",
    "\n",
    "I avoid any plotting on my training servers. However, if you insist on creating plots on the server, you might run into constraints of certain matplotlib backends not being available. If you have a backend that you know is working for your setup, you can select it by prepending any command, for example: `MPLBACKEND=agg python3 -m openpifpaf.train ...`. This would set the backend to `agg` but you can use something else. This works for all Python scripts that use matplotlib.\n",
    "\n",
    "For video on MacOSX, an interactive GUI is required that can update in real-time. I use the matplotlib backend that is called \"macosx\" like this: `MPLBACKEND=macosx python -m openpifpaf.video --source=0 --checkpoint=shufflenetv2k16 --show --long-edge=161`."
   ]
  },
  {
   "cell_type": "markdown",
   "metadata": {},
   "source": [
    "## Predict is slow\n",
    "\n",
    "Check whether your installation of PyTorch can access CUDA for GPU processing.\n",
    "If the output of the command below is False, then PyTorch cannot make use of your GPU and OpenPifPaf falls back to CPU processing."
   ]
  },
  {
   "cell_type": "code",
   "execution_count": null,
   "metadata": {},
   "outputs": [],
   "source": [
    "%%bash\n",
    "python -c \"import torch; print(torch.cuda.is_available())\""
   ]
  },
  {
   "cell_type": "markdown",
   "metadata": {},
   "source": [
    "You can also run `predict` with the `--debug` option. Compare your output with the output in {doc}`predict_cli` to understand which part of the process is slow for you. For a fair comparison, also use `--disable-cuda` because the reference in this documentation is created without CUDA."
   ]
  },
  {
   "cell_type": "markdown",
   "metadata": {},
   "source": [
    "## Python.h or gcc is missing\n",
    "\n",
    "On most systems, you should be able to use a binary wheel (a pre-built binary compilation) so that you don't need to install from source.\n",
    "\n",
    "Source installation might fail with an exception complaining about a missing `Python.h` file or missing `gcc`. This means that you need the development files for Python itself and a C compiler. On Ubuntu systems, you can get this with `sudo apt-get install python3-dev`. For more operating systems, there is a good [StackOverflow post](https://stackoverflow.com/questions/21530577/fatal-error-python-h-no-such-file-or-directory) on the topic."
   ]
  },
  {
   "cell_type": "markdown",
   "metadata": {},
   "source": [
    "## SSL error\n",
    "\n",
    "Your Python environment might not be able to do web requests. You can download a checkpoint yourself in the browser and run all examples with `--checkpoint <pathtoyourcheckpoint>` command line argument."
   ]
  },
  {
   "cell_type": "markdown",
   "metadata": {},
   "source": [
    "## Video output error with openpifpaf.video command\n",
    "\n",
    "Sometimes your system's ffmpeg codecs are not set up. Check that you can run\n",
    "`ffmpeg -codecs` and that you have an `h264` encoder installed. In addition,\n",
    "the below code is a minimal matplotlib example to write a video output\n",
    "that should run without errors on your system:"
   ]
  },
  {
   "cell_type": "code",
   "execution_count": null,
   "metadata": {},
   "outputs": [],
   "source": [
    "import matplotlib.animation\n",
    "import matplotlib.pyplot as plt\n",
    "writer = matplotlib.animation.writers['ffmpeg'](fps=10.0)\n",
    "fig, ax = plt.subplots(1, 1)\n",
    "writer.setup(fig, 'test_animation_output.mp4')\n",
    "writer.grab_frame()\n",
    "writer.finish()"
   ]
  },
  {
   "cell_type": "markdown",
   "metadata": {},
   "source": [
    "## Further resources\n",
    "\n",
    "If nothing helped, check out the system configuration that is printed in\n",
    "the {ref}`dev/Build Environment <build-environment>` section. Run those \n",
    "commands on your system and compare the outputs to see whether there are any\n",
    "significant differences.\n",
    "\n",
    "We also have many \n",
    "[closed issues](https://github.com/openpifpaf/openpifpaf/issues?q=is%3Aissue+is%3Aclosed) \n",
    "that you can search on GitHub and that\n",
    "might contain the answer you are looking for. Also feel free to open a new\n",
    "issue and provide as much information as possible about your problem and \n",
    "the environment you are running in."
   ]
  },
  {
   "cell_type": "code",
   "execution_count": null,
   "metadata": {},
   "outputs": [],
   "source": []
  }
 ],
 "metadata": {
  "kernelspec": {
   "display_name": "Python 3",
   "language": "python",
   "name": "python3"
  },
  "language_info": {
   "name": "python",
   "version": ""
  }
 },
 "nbformat": 4,
 "nbformat_minor": 2
}
